COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	*1 Dec 1974	Subroutine Libraries	LES
C00009 ENDMK
C⊗;
*1 Dec 1974	Subroutine Libraries	LES

File area [SUB,SYS] is allocated for collections of subroutines in text
form.  Each language in use here will have a file named "SUB.<language ext.>".
For example, Sail subroutines (macros and procedures) will be in SUB.SAI.
Supporting load modules and machine language libraries may also be stored
in the area as separate files (no naming conventions at present).

These subroutine collections are to serve two main purposes:
    1) to facilitate the exchange of subroutines among users, so as to
       reduce duplication of effort,
    2) to provide examples of good programming practice in the given
       language, so as to disseminate general techniques and styles.

In order to satisfy these needs, subroutines in these collections should
conform to certain programming and formatting conventions.  General standards
are discussed below, while language-specific standards are treated in the
first page of the corresponding SUB file.  These standards will be
generally permissive.  That is, you may violate them if you state clearly
near the beginning of the accompanying comments that you are an outlaw.

Programmers are invited to add generally useful subroutines to the
appropriate file, usually at the end.  Users of these subroutines
should understand that there is generally no guarantee of correctness,
although the author is obligated to either fix or document known bugs
(see below).

			EDITORS
An editor will be appointed for each language.  His functions wil be to:
1) maintain a set of language-specific standards and conventions on the
   first page of the SUB file;
2) periodically review the collection for correctness and consistency
   with both general and specific standards and bring shortcomings to
   the attention of the authors;
3) purge obsolete subroutines (with the concurrence of the author, if
   present);
4) after the collection matures, organize related groups of subroutines
   into "chapters", each with some guidance on choosing among alternatives;
5) do whatever else is needed to keep his collection from running amok.

			GENERAL STANDARDS
All SUB files will be kept in E format, and more specifically in NEWS
format.  That is, the first line of every page, like the first line of
this page, should be of the form
*<date><tab><topic><tab><author(s) initials>
This will facilitate perusal of these collections using the command:
.R NEWS;SUB.<lang. ext.>[SUB,SYS]

Each group of subroutines on a given topic by a given programmer will
be on a separate page.  All subroutines should conform to good programming
practice and should be fully explained in comments.  While users may
be able to copy your programs into theirs "as is" some of the time, it
will often be necessary to make modifications.  Your comments should
make the operations sufficiently clear that the user will not have to spend
more time figuring it all out than he would take to write a new one.

Conditions that cause the subroutine to fail should be detected and
reported by the subroutine, e.g. by returning a unique value or by
typing an informative error message.  In cases where this is not
possible, the accompanying comments should accurately describe the
conditions under which it fails and what happens.

It is good practice to illustrate the different uses of each subroutine
with some typical calls.  It is even better practice to test the various
modes so as to convince yourself that it actually works as advertised.

			ERRORS
Anyone who sees substandard programming in a subroutine or who encounters
an undocumented failure mode while using it should take it up directly
with the author, if he is still around, or with the Editor.  If the
author believes the complaint, he should either fix it directly or
document it (and, hopefully, fix it later).

If a dispute arises, the Editor my be invited to mediate, or the
complainant may insert a remark denouncing the offending code.  Such
remarks should be on a separate page following the referenced material.

Under no circumstances should anyone touch anyone else's code without
explicit permission of the author (if present) or the editor (otherwise).

			UPDATES
Contributors are free to modify or withdraw their work at any time.
Whenever a change of any kind is made, the date on the top line of
the page should be made current, so as to alert perusers.